Why

Caveman ships 10 SKILL.md files (across skills/, plugins/caveman/skills/, caveman-compress/, compress/, caveman/) and grew from 0 → 30k stars in 11 days. That growth means each new contributor PR that touches a skill file is high-leverage — and also a good place for a small mistake to land silently. Malformed frontmatter, a missing description, or (worst) a committed API key in env would ship to every install.

This PR adds CI that catches those at PR time.

What

A single workflow: .github/workflows/lint-skills.yml — path-filtered to only run when a SKILL.md (or the workflow itself) changes. Uses MukundaKatta/claude-skill-linter (MIT, pinned to @v1) to validate:

• YAML frontmatter parses
• Required fields (name, description) present and well-formed
• name is kebab-case
• description has enough substance (and trigger language) for Claude to route to the skill
• Hardcoded secrets (sk-, ghp_, AIza, xoxb-) are absent
• Relative-path references resolve
• Unknown frontmatter fields flagged (typo detection)

Current state

All 10 existing SKILL.md files pass — in strict mode, zero warnings, zero errors. The workflow starts green.

Ran locally against the repo:

✓ skills/compress/SKILL.md
✓ skills/caveman-review/SKILL.md
✓ skills/caveman-help/SKILL.md
✓ skills/caveman-commit/SKILL.md
✓ skills/caveman/SKILL.md
✓ plugins/caveman/skills/compress/SKILL.md
✓ plugins/caveman/skills/caveman/SKILL.md
✓ compress/SKILL.md
✓ caveman-compress/SKILL.md
✓ caveman/SKILL.md

Checked 10 file(s): 0 error(s), 0 warning(s)

(.cursor/skills/ and .windsurf/skills/ also pass; just not globbed by default since they're in dotfile dirs.)

Why strict mode

For a repo this visible, strict: 'true' is worth the signal — warnings (like missing trigger language in a description) become CI errors. If the noise turns out to be counterproductive on community PRs, flipping it to 'false' is a one-line change. I'd rather start strict and relax if needed than start lax and miss something.

Disclosure

I maintain claude-skill-linter. Happy to unpin @v1 → pin to a specific SHA if you prefer immutability. The Action has no network calls at runtime — all validation is static on the repo's own file contents.

Test plan

• Lints all 10 existing SKILL.md files — green
• Linter source audited: no network, no telemetry, no writes to the workspace
• Workflow path-filtered — won't run on unrelated commits
• Pinned to @v1 (rolling major-version tag)